Skip to content

feat(codelldb): per-platform npm packages as optionalDependencies (esbuild pattern) - #393

Merged
debugmcpdev merged 4 commits into
mainfrom
feat/383-codelldb-platform-packages
Aug 20, 2026
Merged

feat(codelldb): per-platform npm packages as optionalDependencies (esbuild pattern)#393
debugmcpdev merged 4 commits into
mainfrom
feat/383-codelldb-platform-packages

Conversation

@debugmcpdev

Copy link
Copy Markdown
Collaborator

Closes #383. Depends on #392 landing first (the new release step downloads five VSIXs on the runner via the vendor script #392 hardens).

What changed

CodeLLDB now ships as five platform packages — @debugmcp/codelldb-{win32-x64,darwin-x64,darwin-arm64,linux-x64,linux-arm64} — declared as optionalDependencies of @debugmcp/mcp-debugger. npm installs exactly the one matching the host os/cpu (the esbuild pattern), so Rust and C/C++ debugging work out of the box on every platform npm serves, and the CLI tarball shrinks from ~54 MB to ~2.2 MB.

Platform packages

  • Payload shells versioned by the CodeLLDB release (1.11.8), not the repo version: committed content is package.json/README/LICENSE only; binaries are staged at pack time by scripts/stage-codelldb-packages.mjs from the digest-pinned VSIXs (--verify fails if a package would pack without its binaries — npm silently omits missing files entries). sync-versions.cjs skips them via the codelldbPlatform marker; a repo release with an unchanged pin skips republishing ~250 MB via the existing npm-view guards.
  • The win32 package declares cpu: ["x64","arm64"] — no upstream win32-arm64 build exists, so Windows-on-ARM gets the x64 package (emulation).
  • Payload sits at package root, so codelldb-command.ts's dirname(binary)/../lldb derivations work unchanged.

Resolver

New candidate probed after the four vendor-tree candidates and before CODELLDB_PATH, resolved via createRequire from codelldb-common (works from the inlined npx bundle; returns null in monorepo dev where the vendor tree wins — codelldb-common deliberately declares no platform-package dependency, drift-guarded). resolveCodeLLDBExecutableSyncImpl/resolveCodeLLDBExecutable/getCodeLLDBVersion gained injectable hooks so the existing candidate-count tests stay hermetic.

Release pipeline

  • release.yml: "Stage CodeLLDB platform packages" step after the build; a dedicated token-first-publish step before the OIDC step (so the five exist before the CLI referencing them goes live), guarded by npm view @…@$CODELLDB_PKG_VERSION, tagged latest explicitly (CodeLLDB-versioned packages are shared across beta/latest channels); pack dry-run + provenance lists extended.
  • prepare-pack.js now resolves optionalDependencies (the local pack path previously would have shipped literal workspace:*).
  • release-dry-run.sh checks the five against the vendor-manifest pin + manifest completeness.
  • docs/release-checklist.md documents the CodeLLDB bump procedure and the first-publish → trusted-publisher dance.

Degraded modes

  • --omit=optional installs (and the window before first publish): npm ≥11 skips unresolvable optional deps gracefully (verified); the resolver falls through to CODELLDB_PATH with updated error messages at all six adapter sites. The npx test harness retries npm install -g with --omit=optional for older npms.
  • Docker unaffected (shell-vendors + CODELLDB_PATH, untouched).

Verification done

  • stage-codelldb-packages.mjs --verify staged all 5 locally; git stays clean (payload ignored per-package)
  • Full build: tarball 2.2 MB, zero codelldb entries, optionalDependencies resolved to concrete 1.11.8
  • Scratch-dir E2E: installed the CLI tarball + win32 platform tarball in a clean dir, drove it over MCP stdio — a rust session's dry-run spawn resolved …\node_modules\@debugmcp\codelldb-win32-x64\adapter\codelldb.exe --liblldb …\lldb\bin\liblldb.dll
  • Platform-package pack dry-run: 1006 files, 149.8 MB unpacked, 52.7 MB tarball
  • Monorepo regression: rust smoke e2e 4/4 green (vendor tree still wins in dev); codelldb-common suite green incl. new drift guards; npx python e2e green; rust npx smoke self-gates (skips until first publish, arms automatically after)
  • sync-versions.cjs dry run: five reported "pinned to CodeLLDB 1.11.8 (not synced)", no diffs
  • release.yml parses; step order verified

Only verifiable at the next release (record for v0.25.0)

Token first-publish of the five (needs NPM_TOKEN still present), provenance on them, real npm os/cpu selection across platforms, and the npm-view skip-guards on the release after. Afterwards: configure five trusted publishers and move them into the OIDC step (checklist updated).

🤖 Generated with Claude Code

cynarlab and others added 2 commits August 20, 2026 15:50
…build pattern)

Closes #383. CodeLLDB now ships as five platform packages —
@debugmcp/codelldb-{win32-x64,darwin-x64,darwin-arm64,linux-x64,linux-arm64}
— declared as optionalDependencies of @debugmcp/mcp-debugger, so npm
installs exactly the one matching the host os/cpu. Rust and C/C++
debugging work out of the box on every platform npm serves, and the CLI
tarball shrinks from ~54 MB to ~2 MB (it previously bundled linux-x64).

- Platform packages are payload shells versioned by the CodeLLDB release
  (1.11.8): committed manifest/README/LICENSE only, binaries staged at
  pack time by scripts/stage-codelldb-packages.mjs from the digest-pinned
  VSIXs (--verify guards against publishing a near-empty package). The
  win32 package allows cpu arm64 (x64 emulation; no upstream arm64 build).
- Resolver: new platform-package candidate probed after the four vendor
  candidates and before CODELLDB_PATH, via createRequire so it works from
  the inlined npx bundle; monorepo dev resolution stays vendor-tree-first
  (codelldb-common deliberately declares no platform-package dependency).
- Release: staging + token-first-publish steps in release.yml (guarded by
  npm-view at the CodeLLDB version, tagged latest explicitly), pack/
  provenance lists extended, release-dry-run checks the five against the
  vendor-manifest pin, sync-versions skips codelldbPlatform-marked
  packages, prepare-pack resolves optionalDependencies.
- Tests: resolver candidate-order coverage, package.json drift guards,
  plain-node hermeticity probe, self-gating rust npx smoke (arms after
  first publish), npm install -g retry with --omit=optional in the npx
  harness for the pre-publish window.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@codecov

codecov Bot commented Aug 20, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

cynarlab and others added 2 commits August 20, 2026 16:37
…idempotency, drift guards

Review follow-ups on the platform-packages PR:

- Resolver precedence: the installed @debugmcp/codelldb-* package is now
  the LAST resort — vendor tree, then CODELLDB_PATH, then the package —
  so an explicit env override survives the upgrade (three reviewers
  flagged the silent shadowing). The require.resolve walk is lazy and
  memoized per platform dir; getCodeLLDBVersion reads version.json as a
  sibling of the binary it actually resolved before falling back to the
  candidate walk (no more cross-install misattribution).
- Release idempotency: the platform-package publish guard distinguishes
  E404 from transient npm-view failures ("already exists" is the normal
  path at an unchanged pin — a hiccup must not publish over an existing
  version and kill the job); the token .npmrc is removed via an EXIT trap;
  staging and --verify-only run as separate processes so a silently-dying
  vendor process cannot vouch for itself (#389 coupling).
- One source of truth: stage-codelldb-packages.mjs derives platforms and
  payload layout from the vendor script's exported PLATFORMS, drops its
  duplicate freshness check (downloadAndExtract already has one), stages
  in parallel, uses a single failure channel, and extends exec-bit checks
  to lldb/bin helpers (warning loudly on a Windows staging host, where
  NTFS cannot represent them). sync-versions.cjs now WRITES the
  vendor-manifest pin into any workspace package declaring os/cpu — a
  CodeLLDB bump is just "edit manifest + DEFAULT_CODELLDB_VERSION, run
  sync" — replacing the codelldbPlatform marker field, which is dropped.
- Drift guards: new tests pin release.yml's and release-dry-run.sh's
  five-platform lists to SUPPORTED_CODELLDB_PLATFORM_DIRS, assert every
  declared os/cpu combo maps back through getCodeLLDBPlatformDir (the
  win32-arm64 emulation contract), and forbid an exports map on the
  payload shells (it would break the resolver's package.json resolve).
  Platform-package READMEs no longer hardcode the CodeLLDB version.
- Test hygiene: the npx install retry now fires only on E404/ETARGET
  naming @debugmcp/codelldb-* (any other failure stays loud); the rust
  npx smoke imports the real resolver helpers instead of private copies
  and timeboxes its collection-time registry probe; dry-run command
  substitutions fail as red checklist lines instead of aborting under
  set -e; bundle-cli's default is '' (the 'none' sentinel remains as the
  explicit escape hatch).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@debugmcpdev
debugmcpdev merged commit 72010ab into main Aug 20, 2026
8 of 9 checks passed
@debugmcpdev
debugmcpdev deleted the feat/383-codelldb-platform-packages branch August 20, 2026 21:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Package CodeLLDB as per-platform optionalDependencies (esbuild pattern)

2 participants